Route parameters

Route parameters define a fixed value which is associated with a qualified name.

• Routing: Route parameters which allow the controller to distinguish branches easily and route the request accordingly.

• Rendering: The system will select a route to render an URL if all route parameters are always matched.

  <route path="/foo">
    <route-param qname="gtn:handler">
      <value>portal</value>
    </route-param>
  </route>

  This configuration matches the "/foo" request path to the map (gtn:handler=portal). Conversely, it renders the map (gtn:handler=portal) as the "/foo" URL. This example shows two concepts:

• Exact path matching ("/foo").

• Route parameters ("gtn:handler").

Path parameters - _Regular expression support _

Path parameters allow associating a portion of the request path with a parameter. Such parameter will match any non empty portions of text except the / character (that is the [^/]+ regular expression). Otherwise, they can be associated with a regular expression for matching specific patterns. Path parameters are mandatory for matching since they are a part of the request path, however it is allowed to write regular expression matching an empty value.

• Routing: Route is accepted if the regular expression is matched.

• Rendering: The system will select a route to render an URL if all route parameters are always matched.
  Encoding

Path parameters may contain the '/' character which is a reserved char for the URI path. This case is specially handled by the navigation controller by using a special character to replace the '/' literals. By default, the character is the colon (":") and can be changed to other possible values (see controller XML schema for possible values) to give a greater amount of flexibility.

This encoding is applied only when the encoding is performed for parameters having a mode set to the default-form value, for instance, it does not happen for navigation node URI (for which / are encoded literally). The separator escape char can still be used but under it is percent escaped form, so by default, a path parameter value containing the colon ":" would be encoded as %3A and conversely the %3A value will be decoded as the colon ":".

<route path="/{gtn:path}">
</route>

As a result, routing and rendering are as below:

Routing and Rendering
Path "/foo"      <--> the map (gtn:path=foo)

Path "/foo:bar"  <--> the map (gtn:path=foo/bar)

If the request path contains another "/" char, it will not work. The default encoding mode is default-form. In the example above, "/foo/bar" is not matched, so the system returns an empty parameter map.

However, this problem could be solved with the following configuration:

<route path="/{gtn:path}">
  <path-param encoding="preserve-path" qname="gtn:path">
    <pattern>.*</pattern>
  </path-param>
</route>

• The ".*" declaration allows matching any char sequence.

• The "preserve-path" encoding tells the engine that the "/" chars should be handled by the path parameter itself as they have a special meaning for the router. Without this special encoding, "/" would be rendered as the ":" character and conversely the ":" character would be matched as the "/" character.

Request parameters

Request parameters are matched from the request parameters (GET or POST). The match can be optional as their representation in the request allows it.

• Routing:

  • Route is accepted when a required parameter is present and matched in the request.

  • Route is accepted when an optional parameter is absent or matched in the request.

• Rendering:

  • For required parameters, the system will select a route to render an URL when the parameter is present and matched in the map.

  • For optional parameters, the system will select a route to render an URL when the parameter is absent or matched in the map.

    <route path="/">
      <request-param name="path" qname="gtn:path"/>
    </route>

    Request parameters are declared by a request-param element and will match any value by default. A request like "/?path=foo" is mapped to the map (gtn:path=foo). The name attribute of the request-param tag defines the request parameter value. This element accepts more configuration:

• A value or a pattern element that is a child element used to match a constant or a pattern.

• A control-mode attribute with the optional or required value indicates if matching is mandatory or not.

• A value-mapping attribute with the possible values, such as canonical, never-empty, never-null can be used to filter values after matching is done. For instance, a parameter configured with value-mapping="never-empty" and matched with the empty string value will not put the empty string in the map.

Route precedence

The order of route declaration is important as it affects how rules are matched. Sometimes, the same request could be matched by several routes and the routing table is ambiguous.

<route path="/foo">
  <route-param qname="gtn:handler">
    <value>portal</value>
  </route-param>
</route>
<route path="/{gtn:path}">
  <path-param encoding="preserve-path" qname="gtn:path">
    <pattern>.*</pattern>
  </path-param>
</route>

In that case, the request path "/foo" will always be matched by the first rule before the second rule. This can be misleading since the map (gtn:path=foo) would be rendered as "/foo" and would not be matched by the first rule. Such ambiguity can happen, it can be desirable or not.

Route nesting

Route nesting is possible and often desirable as it helps to:

• Factor common parameters in a common rule.

• Perform more efficient matching as the match of the common rule is done once for all the sub routes.

  <route path="/foo">
    <route-param qname="gtn:handler">
      <value>portal</value>
    </route-param>
    <route path="/bar">
      <route-param qname="gtn:path">
        <value>bar</value>
      </route-param>
    </route>
    <route path="/juu">
      <route-param qname="gtn:path">
        <value>juu</value>
      </route-param>
    </route>
  </route>

• The request path "/foo/bar" is mapped to the (gtn:handler=portal,gtn:path=bar) map.

• The request path "/foo/juu" is mapped to the (gtn:handler=portal,gtn:path=juu) map.

• The request path "/foo" is not mapped as non leaf routes do not perform matches.

PortalURL

PortalURL plays a similar role at the portal level. Its main role is to abstract the creation of an URL for a resource managed by the portal.

public abstract class PortalURL<R, U extends PortalURL<U>>
{
   ...
}

The PortalURL declaration may seem a bit strange at first sight with two generic types: U and R.

• The R generic type represents the type of the resource managed by the portal.

• The U generic type is also described as self bound generic type. This design pattern allows a class to return subtypes of itself in the class declaring the generic type. Java Enums are based on this principle (class Enum<E extends Enum<E>>).
  A portal URL has various methods but certainly the most important method is the toString() method that generates an URL targeting to the resource. The remaining methods are getter and setter used to mutate the URL configuration, those options will affect the URL representation when it is generated.

• resource: The mandatory resource associated with the URL.

• locale: The optional locale used in the URL allowing the creation of bookmarkable URL containing a language.

• confirm: The optional confirmation message displayed by the portal in the context of the portal UI.

• ajax: The ajax option allowing an ajax invocation of the URL.
  Obtaining a PortalURL

PortalURL objects are obtained from RequestContext instance, such as PortalRequestContext, or PortletRequestContext. Usually, those are obtained thanks to the getCurrentInstance method of the RequestContext class:

RequestContext ctx = RequestContext.getCurrentInstance();

PortalURL is created via the createURL method that takes an input as a resource type. The resource type is usually a constant and type-safe object that allows retrieving the PortalURL subclasses:

RequestContext ctx = RequestContext.getCurrentInstance();
PortalURL<R, U> url = ctx.createURL(type);

In reality, you will use a concrete type constant and have instead more concrete code like:

RequestContext ctx = RequestContext.getCurrentInstance();
NodeURL url = ctx.createURL(NodeURL.TYPE);

NodeURL

The NodeURL class is one of the subclass of PortalURL that is specialized in navigation node resources:

public class NodeURL extends PortalURL<NavigationResource, NodeURL>
{
   ...
}

The NodeURL class does not carry any generic types of its super class, which means that a NodeURL is type-safe and you do not have to worry about generic types.

Using a NodeURL is pretty straightforward:

NodeURL url = RequestContext.getCurrentInstance().createURL(NodeURL.TYPE);
url.setResource(new NavigationResource("portal", "classic, "home"));
String s = url.toString();

The NodeURL subclass contains the specialized setter methods to make its usage even easier:

UserNode node = ...;
NodeURL url = RequestContext.getCurrentInstance().createURL(NodeURL.TYPE);
url.setNode(node);
String s = url.toString();

ComponentURL

The ComponentURL subclass is another specialization of PortalURL that allows the creation of WebUI components URLs. ComponentURL is commonly used to trigger WebUI events from client side:

<% def componentURL = uicomponent.event(...); /*or uicomponent.url(...) */ %>
<a href=$componentURL>Click me</a>

Normally, you should not have to deal with it as the WebUI framework has already an abstraction for managing URL known as URLBuilder. The URLBuilder implementation delegates URL creation to ComponentURL objects.

Portlet URLs

Portlet URLs API implementation delegates to the portal ComponentURL (via the portlet container SPI). It is possible to control the language in the URL from a PortletURL object by setting the gtn:lang property:

• When the property value is set to a value returned by the Locale#toString() method for locale objects having a non null language value and a null variant value, the URL generated by the PortletURL#toString() method will contain the locale in the URL.

• When the property value is set to an empty string, the generated URL will not contain a language. If the incoming URL was carrying a language, this language will be erased.

• When the property value is not set, it will not affect the generated URL.

  PortletURL url = resp.createRenderURL();
  url.setProperty("gtn:lang", "fr");
  writer.print("<a href='" + url + "'>French</a>");

Webui URLBuilder

This internal API used to create URL works as usual and delegates to the PortletURL API when the framework is executed in a portlet, and delegates to a ComponentURL API when the framework is executed in the portal context. The API has been modified to take in account the language in URL with two properties on the builder:

• locale: A locale for setting on the URL.

• removeLocale: A boolean for removing the locale present on the URL.

Groovy Templates

In a Groovy template, the mechanism to create an URL is the same as the way of APIs above, however a splash of integration has been done to make creation of NodeURL simpler. A closure is bound under the nodeurl name and is available for invocation anytime. It will simply create a NodeURL object and return it:

UserNode node = ...;
NodeURL url = nodeurl();
url.setNode(node);
String s = url.toString();

The nodeurl closure is bound to Groovy template in WebuiBindingContext.

// Closure nodeurl()
put("nodeurl", new Closure(this)
{
  @Override
  public Object call(Object[] args)
  {
    return context.createURL(NodeURL.TYPE);
  }
});